nnmaildir stores mail in
the maildir format, with each maildir corresponding to a group in
Gnus. This format is documented here: http://cr.yp.to/proto/maildir.html
and here: http://www.qmail.org/man/man5/maildir.html.
nnmaildir also stores extra information in the
.nnmaildir/ directory
within a maildir.
Maildir format was designed to allow concurrent deliveries and
reading, without needing locks. With other back ends, you would
have your mail delivered to a spool of some kind, and then you
would configure Gnus to split mail from that spool into your
groups. You can still do that with nnmaildir, but
the more common configuration is to have your mail delivered
directly to the maildirs that appear as group in Gnus.
nnmaildir is designed to be perfectly reliable:
C-g will never corrupt its data in memory, and
SIGKILL will never corrupt its data in the
filesystem.
nnmaildir stores article marks and
NOV data in each maildir. So you can copy a
whole maildir from one Gnus setup to another, and you will keep
your marks.
Virtual server settings:
directorynnmaildir servers (it's very
unlikely that you'd need more than one), you need to create a
directory and populate it with maildirs or symlinks to
maildirs (and nothing else; do not choose a directory already
used for other purposes). Each maildir will be represented in
Gnus as a newsgroup on that server; the filename of the
symlink will be the name of the group. Any filenames in the
directory starting with ‘.’ are ignored. The directory is
scanned when you first start Gnus, and each time you type
g in the group buffer; if any maildirs have been
removed or added, nnmaildir notices at these
times.
The value of the directory parameter should
be a Lisp form which is processed by eval and
expand-file-name to get the path of the
directory for this server. The form is evaled
only when the server is opened; the resulting string is used
until the server is closed. (If you don't know about forms
and eval, don't worry—a simple string will
work.) This parameter is not optional; you must specify it. I
don't recommend using "~/Mail" or a subdirectory
of it; several other parts of Gnus use that directory by
default for various things, and may get confused if
nnmaildir uses it too.
"~/.nnmaildir" is a typical value.
target-prefixeval and expand-file-name. The form
is evaled only when the server is opened; the
resulting string is used until the server is closed.
When you create a group on an nnmaildir
server, the maildir is created with
target-prefix prepended to its name, and a
symlink pointing to that maildir is created, named with the
plain group name. So if directory is
"~/.nnmaildir" and target-prefix is
"../maildirs/", then when you create the group
foo, nnmaildir will create
~/.nnmaildir/../maildirs/foo as a
maildir, and will create ~/.nnmaildir/foo as a symlink pointing
to ../maildirs/foo.
You can set target-prefix to a string without
any slashes to create both maildirs and symlinks in the same
directory; in this case, any maildirs found in
directory whose names start with
target-prefix will not be listed as groups (but
the symlinks pointing to them will be).
As a special case, if target-prefix is
"" (the default), then when you create a group,
the maildir will be created in directory without
a corresponding symlink. Beware that you cannot use
gnus-group-delete-group on such groups without
the force argument.
directory-filesdirectory-files (such as
directory-files itself). It is used to scan the
server's directory for maildirs. This parameter is
optional; the default is
nnheader-directory-files-safe if
nnheader-directory-files-is-safe is
nil, and directory-files otherwise.
(nnheader-directory-files-is-safe is checked only
once when the server is opened; if you want to check it each
time the directory is scanned, you'll have to provide your own
function that does that.)get-new-mailnil, then after scanning for new mail in
the group maildirs themselves as usual, this server will also
incorporate mail the conventional Gnus way, from
mail-sources according to
nnmail-split-methods or
nnmail-split-fancy. The default value is
nil.
Do not use the same maildir both in
mail-sources and as an nnmaildir
group. The results might happen to be useful, but that would
be by chance, not by design, and the results might be
different in the future. If your split rules create new
groups, remember to supply a create-directory
server parameter.
nnmaildir uses several group parameters. It's
safe to ignore all this; the default behavior for
nnmaildir is the same as the default behavior for
other mail back ends: articles are deleted after one week, etc.
Except for the expiry parameters, all this functionality is
unique to nnmaildir, so you can ignore it if you're
just trying to duplicate the behavior you already have with
another back end.
If the value of any of these parameters is a vector, the first
element is evaluated as a Lisp form and the result is used,
rather than the original value. If the value is not a vector, the
value itself is evaluated as a Lisp form. (This is why these
parameters use names different from those of other, similar
parameters supported by other back ends: they have different,
though similar, meanings.) (For numbers, strings,
nil, and t, you can ignore the
eval business again; for other values, remember to
use an extra quote and wrap the value in a vector when
appropriate.)
expire-agenever to specify that articles should never be
expired. If this parameter is not set, nnmaildir
falls back to the usual
nnmail-expiry-wait(-function)
variables (the expiry-wait group parameter
overrides nnmail-expiry-wait and makes
nnmail-expiry-wait-function ineffective). If you
wanted a value of 3 days, you could use something like
[(* 3 24 60 60)]; nnmaildir will
evaluate the form and use the result. An article's age is
measured starting from the article file's modification time.
Normally, this is the same as the article's delivery time, but
editing an article makes it younger. Moving an article (other
than via expiry) may also make an article younger.expire-group
"backend+server.address.string:group.name"
and if it is not the name of the same group that the
parameter belongs to, then articles will be moved to the
specified group during expiry before being deleted. If
this is set to an nnmaildirgroup, the
article will be just as old in the destination group as it
was in the source group. So be careful with
expire-age in the destination group. If this is
set to the name of the same group that the parameter belongs
to, then the article is not expired at all. If you use the
vector form, the first element is evaluated once for each
article. So that form can refer to
nnmaildir-article-file-name, etc., to decide
where to put the article. Even if this parameter is not
set, nnmaildirdoes not fall back to
the expiry-target group parameter or
the nnmail-expiry-target
variable.
read-onlyt, nnmaildir
will treat the articles in this maildir as read-only. This
means: articles are not renamed from new/ into cur/; articles are only found in
new/, not
cur/; articles are never
deleted; articles cannot be edited. new/ is expected to be a symlink to the
new/ directory of
another maildir—e.g., a system-wide mailbox containing a
mailing list of common interest. Everything in the maildir
outside new/ is
not treated as read-only, so for a shared mailbox, you
do still need to set up your own maildir (or have write
permission to the shared mailbox); your maildir just won't
contain extra copies of the articles.directory-filesdirectory-files. It is used to scan the
directories in the maildir corresponding to this group to find
articles. The default is the function specified by the server's
directory-files parameter.distrust-Lines:nil, nnmaildir will always
count the lines of an article, rather than use the
Lines: header field. If nil, the
header field will be used if present.always-marks['(read
expire)]. Whenever Gnus asks nnmaildir for
article marks, nnmaildir will say that all
articles have these marks, regardless of whether the marks
stored in the filesystem say so. This is a proof-of-concept
feature that will probably be removed eventually; it ought to
be done in Gnus proper, or abandoned if it's not
worthwhile.never-marks['(tick
expire)]. Whenever Gnus asks nnmaildir for
article marks, nnmaildir will say that no articles
have these marks, regardless of whether the marks stored in the
filesystem say so. never-marks overrides
always-marks. This is a proof-of-concept feature
that will probably be removed eventually; it ought to be done
in Gnus proper, or abandoned if it's not worthwhile.nov-cache-sizennmaildir keeps NOV data in
memory for a limited number of articles in each group. (This is
probably not worthwhile, and will probably be removed in the
future.) This parameter's value is noticed only the first time
a group is seen after the server is opened—i.e., when you
first start Gnus, typically. The NOV cache
is never resized until the server is closed and reopened. The
default is an estimate of the number of articles that would be
displayed in the summary buffer: a count of articles that are
either marked with tick or not marked with
read, plus a little extra.Articles are stored in the cur/ subdirectory of each maildir. Each
article file is named like uniq:info, where
uniq contains no colons. nnmaildir
ignores, but preserves, the :info part. (Other
maildir readers typically use this part of the filename to store
marks.) The uniq part uniquely identifies the
article, and is used in various places in the .nnmaildir/ subdirectory of the maildir to
store information about the corresponding article. The full
pathname of an article is available in the variable
nnmaildir-article-file-name after you request the
article in the summary buffer.
An article identified by uniq has its
NOV data (used to generate lines in the
summary buffer) stored in .nnmaildir/nov/uniq. There
is no nnmaildir-generate-nov-databases function.
(There isn't much need for it—an article's
NOV data is updated automatically when the
article or nnmail-extra-headers has changed.) You
can force nnmaildir to regenerate the
NOV data for a single article simply by
deleting the corresponding NOV file, but
beware: this will also cause nnmaildir to
assign a new article number for this article, which may cause
trouble with seen marks, the Agent, and the
cache.
An article identified by uniq is considered to
have the mark flag when the file .nnmaildir/marks/flag/uniq exists. When Gnus
asks nnmaildir for a group's marks,
nnmaildir looks for such files and reports the set
of marks it finds. When Gnus asks nnmaildir to store
a new set of marks, nnmaildir creates and deletes
the corresponding files as needed. (Actually, rather than create
a new file for each mark, it just creates hard links to
.nnmaildir/markfile, to
save inodes.)
You can invent new marks by creating a new directory in
.nnmaildir/marks/. You can
tar up a maildir and remove it from your server, untar it later,
and keep your marks. You can add and remove marks yourself by
creating and deleting mark files. If you do this while Gnus is
running and your nnmaildir server is open, it's best
to exit all summary buffers for nnmaildir groups and
type s in the group buffer first, and to type
g or M-g in the group buffer afterwards.
Otherwise, Gnus might not pick up the changes, and might undo
them.